src/instant_messaging/index.ts (1)

4-12: Use @/ aliases for the new barrel re-exports.

These new exports are still wired through relative paths. Switching them to the repository alias keeps this public entrypoint aligned with the SDK import convention.

♻️ Proposed change

-export { L2PSMessagingPeer } from "./L2PSMessagingPeer"
+export { L2PSMessagingPeer } from "@/instant_messaging/L2PSMessagingPeer"
 export type {
     L2PSMessagingConfig,
     L2PSMessageHandler,
     L2PSErrorHandler,
     L2PSPeerHandler,
     L2PSConnectionStateHandler,
-} from "./L2PSMessagingPeer"
-export * from "./l2ps_types"
+} from "@/instant_messaging/L2PSMessagingPeer"
+export * from "@/instant_messaging/l2ps_types"

As per coding guidelines, "Use @/ path aliases instead of relative imports".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/instant_messaging/index.ts` around lines 4 - 12, The current barrel in
index.ts exports L2PSMessagingPeer and related types via relative paths; update
these to use the repository path alias (e.g., replace "./L2PSMessagingPeer" and
"./l2ps_types" with the corresponding "@/..." alias) so the public entrypoint
follows the SDK import convention; ensure the exported symbols
L2PSMessagingPeer, L2PSMessagingConfig, L2PSMessageHandler, L2PSErrorHandler,
L2PSPeerHandler, L2PSConnectionStateHandler and the re-export of l2ps_types all
reference the alias form.

src/instant_messaging/L2PSMessagingPeer.ts (1)

57-80: Model IncomingFrame as a discriminated union and type the pending metadata storage instead of using as any casts.

IncomingFrame.payload, pendingResponses value types, and the _meta attachment patterns all use any, bypassing type checking where frames are parsed and matched. Replace IncomingFrame with a union of the imported server response types (e.g., RegisteredResponse | IncomingMessage | MessageSentResponse | ...), and refactor the pending entry storage to include a properly typed meta property instead of mutating via (entry as any)._meta.

Per coding guidelines: "Ensure full TypeScript type coverage."

Also applies to: 416–469

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/instant_messaging/L2PSMessagingPeer.ts` around lines 57 - 80, Replace the
ad-hoc IncomingFrame and the any-typed pendingResponses values with proper typed
constructs: change IncomingFrame to a discriminated union of the actual server
response interfaces (e.g., RegisteredResponse | IncomingMessage |
MessageSentResponse | ... using the existing ServerMessageType discriminant),
and update the pendingResponses Map value type to an interface that includes
resolve, reject, timer and a typed meta property (e.g., meta?: PendingMetaType)
so you stop using (entry as any)._meta; then update parsing/dispatch logic in
L2PSMessagingPeer where frames are parsed and where pendingResponses entries are
created/mutated to use entry.meta (with the correct type) and pattern-match on
the discriminant to narrow payload types instead of treating payload as any.

✅ Autofix completed

src/instant_messaging/L2PSMessagingPeer.ts (5)

165-170: Remove unused loop variable.

The key variable is extracted but never used. Either prefix it with underscore to indicate intentional discard, or iterate over values only.

🧹 Proposed fix

         // Reject all pending responses
-        for (const [key, pending] of this.pendingResponses) {
+        for (const [_key, pending] of this.pendingResponses) {
             clearTimeout(pending.timer)
             pending.reject(new Error("Disconnected"))
         }

Or simpler:

         // Reject all pending responses
-        for (const [key, pending] of this.pendingResponses) {
+        for (const pending of this.pendingResponses.values()) {
             clearTimeout(pending.timer)
             pending.reject(new Error("Disconnected"))
         }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/instant_messaging/L2PSMessagingPeer.ts` around lines 165 - 170, The loop
over this.pendingResponses extracts an unused key; update the iteration to avoid
the unused variable by iterating values only (e.g., use
this.pendingResponses.values() or destructure to skip the key with an
underscore) so you still call clearTimeout(pending.timer) and pending.reject(new
Error("Disconnected")) and then call this.pendingResponses.clear(); keep
references to pending.timer and pending.reject intact.

---

13-29: Remove unused imports and consider using path alias.

Static analysis indicates StoredMessage, PeerJoinedNotification, and PeerLeftNotification are imported but never used. Additionally, per coding guidelines, prefer @/ path aliases over relative imports.

🧹 Proposed fix

 import type {
     SerializedEncryptedMessage,
     ClientMessageType,
     ServerMessageType,
     RegisteredResponse,
     IncomingMessage,
     MessageSentResponse,
     MessageQueuedResponse,
     HistoryResponse,
     DiscoverResponse,
     PublicKeyResponse,
-    PeerJoinedNotification,
-    PeerLeftNotification,
     ErrorResponse,
     ErrorCode,
-    StoredMessage,
-} from "./l2ps_types"
+} from "@/instant_messaging/l2ps_types"

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/instant_messaging/L2PSMessagingPeer.ts` around lines 13 - 29, Remove the
unused imports StoredMessage, PeerJoinedNotification, and PeerLeftNotification
from the import list in L2PSMessagingPeer (they are not referenced anywhere in
this file) and update the module import path from the relative "./l2ps_types" to
the project path alias "@/instant_messaging/l2ps_types" (or the appropriate
"@/..." alias used in the repo) so the import uses the canonical alias per
guidelines; ensure only the actually used types (e.g.,
SerializedEncryptedMessage, ClientMessageType, ServerMessageType,
RegisteredResponse, IncomingMessage, MessageSentResponse, MessageQueuedResponse,
HistoryResponse, DiscoverResponse, PublicKeyResponse, ErrorResponse, ErrorCode)
remain in the import statement.

---

78-82: Consider integrating PendingMeta into the pending response type.

Using (entry as any)._meta to attach metadata is fragile. Integrating the metadata into the Map's value type would improve type safety.

🧹 Proposed fix

+interface PendingResponseEntry {
+    resolve: (value: any) => void
+    reject: (error: Error) => void
+    timer: NodeJS.Timeout
+    expectedTypes: ServerMessageType[]
+}

     // Pending request-response waiters
-    private pendingResponses: Map<
-        string,
-        { resolve: (value: any) => void; reject: (error: Error) => void; timer: NodeJS.Timeout }
-    > = new Map()
+    private readonly pendingResponses: Map<string, PendingResponseEntry> = new Map()

Then update waitForResponse:

-            const entry = { resolve, reject, timer }
-            // Attach metadata for matching
-            ;(entry as any)._meta = { types: expectedTypes } as PendingMeta
-            this.pendingResponses.set(requestId, entry)
+            this.pendingResponses.set(requestId, { resolve, reject, timer, expectedTypes })

And handleFrame:

-            const meta = (pending as any)._meta as PendingMeta | undefined
-            if (meta?.types.includes(frame.type)) {
+            if (pending.expectedTypes.includes(frame.type)) {

Also applies to: 516-519

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/instant_messaging/L2PSMessagingPeer.ts` around lines 78 - 82, The
pendingResponses Map currently stores value objects without typed metadata and
code uses (entry as any)._meta; introduce a PendingMeta type and change the Map
value type to include meta, e.g. { resolve, reject, timer, meta: PendingMeta },
then update any places that create or read entries (notably waitForResponse and
handleFrame) to set and read entry.meta instead of using (entry as any)._meta so
the metadata is strongly typed and you can drop the casts; also update other
similar maps/usages around lines referenced (516-519) to the same typed shape.

---

459-479: Simplify frame handling with optional chaining and remove unnecessary assertions.

The non-null assertions after .has() checks are redundant. Use optional chaining for cleaner code.

🧹 Proposed fix

     private handleFrame(frame: IncomingFrame): void {
         // First, check if any pending response matches by requestId
-        if (frame.requestId && this.pendingResponses.has(frame.requestId)) {
-            const pending = this.pendingResponses.get(frame.requestId)!
+        if (frame.requestId) {
+            const pending = this.pendingResponses.get(frame.requestId)
+            if (!pending) {
+                // No waiter, fall through to event dispatch
+            } else {
             const meta = (pending as any)._meta as PendingMeta | undefined
-            if (meta && meta.types.includes(frame.type)) {
+            if (meta?.types.includes(frame.type)) {
                 clearTimeout(pending.timer)
                 this.pendingResponses.delete(frame.requestId)
                 pending.resolve(frame.payload)
                 return
             }
+            }
         }

         // Handle error frames with requestId
-        if (frame.type === "error" && frame.requestId && this.pendingResponses.has(frame.requestId)) {
-            const pending = this.pendingResponses.get(frame.requestId)!
+        if (frame.type === "error" && frame.requestId) {
+            const pending = this.pendingResponses.get(frame.requestId)
+            if (pending) {
             clearTimeout(pending.timer)
             this.pendingResponses.delete(frame.requestId)
             pending.reject(new Error(frame.payload?.message || "Server error"))
             return
+            }
         }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/instant_messaging/L2PSMessagingPeer.ts` around lines 459 - 479, In
handleFrame, remove redundant non-null assertions after Map.has() by using
optional chaining and early-returns: when checking
this.pendingResponses.has(frame.requestId) replace the get(...)! usage with
const pending = this.pendingResponses.get(frame.requestId); guard with if
(!pending) return; use pending?._meta and pending?.timer etc.; similarly in the
error frame block get the pending via get and guard instead of using !, and use
optional chaining for frame.payload?.message when constructing the Error; ensure
you still clearTimeout, delete from this.pendingResponses, and call
pending.resolve/pending.reject as before.

---

68-96: Mark non-reassigned members as readonly.

Static analysis correctly identifies that several class members are never reassigned. Marking them readonly prevents accidental mutation and clarifies intent.

🧹 Proposed fix

 export class L2PSMessagingPeer {
     private ws: WebSocket | null = null
-    private config: L2PSMessagingConfig
+    private readonly config: L2PSMessagingConfig

     // Event handlers
-    private messageHandlers: Set<L2PSMessageHandler> = new Set()
-    private errorHandlers: Set<L2PSErrorHandler> = new Set()
-    private peerJoinedHandlers: Set<L2PSPeerHandler> = new Set()
-    private peerLeftHandlers: Set<L2PSPeerHandler> = new Set()
-    private connectionStateHandlers: Set<L2PSConnectionStateHandler> = new Set()
+    private readonly messageHandlers: Set<L2PSMessageHandler> = new Set()
+    private readonly errorHandlers: Set<L2PSErrorHandler> = new Set()
+    private readonly peerJoinedHandlers: Set<L2PSPeerHandler> = new Set()
+    private readonly peerLeftHandlers: Set<L2PSPeerHandler> = new Set()
+    private readonly connectionStateHandlers: Set<L2PSConnectionStateHandler> = new Set()

     // Pending request-response waiters
-    private pendingResponses: Map<
+    private readonly pendingResponses: Map<
         string,
         { resolve: (value: any) => void; reject: (error: Error) => void; timer: NodeJS.Timeout }
     > = new Map()

     // State
     private _isConnected = false
     private _isRegistered = false
     private onlinePeers: Set<string> = new Set()
-    private messageQueue: OutgoingFrame[] = []
+    private readonly messageQueue: OutgoingFrame[] = []

     // Reconnection
     private reconnectAttempts = 0
-    private maxReconnectAttempts = 10
-    private baseReconnectDelay = 1000
+    private readonly maxReconnectAttempts = 10
+    private readonly baseReconnectDelay = 1000

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/instant_messaging/L2PSMessagingPeer.ts` around lines 68 - 96, Several
instance fields in L2PSMessagingPeer are never reassigned; mark them readonly to
prevent accidental reassignment. Update the declarations in class
L2PSMessagingPeer for config, messageHandlers, errorHandlers,
peerJoinedHandlers, peerLeftHandlers, connectionStateHandlers, pendingResponses,
onlinePeers, messageQueue, baseReconnectDelay, and maxReconnectAttempts to
include the readonly modifier (leave fields that are mutated such as ws,
_isConnected, _isRegistered, reconnectAttempts, reconnectTimeout,
shouldReconnect, isReconnecting unchanged). This keeps existing mutation of
collection contents intact while preventing reassignment of the references.

src/instant_messaging/l2ps_types.ts (1)

229-237: Consider adding a "read" status for delivery receipts.

The MessageStatus type covers the message lifecycle well, but lacks a status for when the recipient has read the message. If read receipts are planned, consider adding this now to avoid a breaking change later.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/instant_messaging/l2ps_types.ts` around lines 229 - 237, The
MessageStatus union type is missing a "read" state for delivery receipts; update
the MessageStatus type definition (the exported type named MessageStatus in
l2ps_types.ts) to include a "read" variant (e.g., | "read") and ensure any
switch/case, serializers, database enums, and tests that consume MessageStatus
are updated to handle the new "read" value so this addition won't break type
narrowing elsewhere.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

AGENTS.md (1)

244-246: Add a language specifier to the fenced code block.

The code block lacks a language identifier. Since this is a pseudo-code formula, consider using text or plaintext to satisfy markdown linters.

📝 Proposed fix

-```
+```text
 score = urgency + (blocked_tasks_count × 1.5)

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @AGENTS.md around lines 244 - 246, The fenced code block showing the formula
"score = urgency + (blocked_tasks_count × 1.5)" is missing a language specifier;
update the markdown fence to include a language such as "text" or "plaintext" so
linters recognize it as plain text (referencing the formula symbols score,
urgency, and blocked_tasks_count), e.g., change totext and keep the
formula unchanged.

</details>

</blockquote></details>
<details>
<summary>src/instant_messaging/L2PSMessagingPeer.ts (5)</summary><blockquote>

`180-183`: **Use `_` for the unused loop variable.**

The `key` variable is declared but never used. Use `_` to indicate intentional discard.

<details>
<summary>🧹 Proposed fix</summary>

```diff
-        for (const [key, pending] of this.pendingResponses) {
+        for (const [_, pending] of this.pendingResponses) {
             clearTimeout(pending.timer)
             pending.reject(new Error("Disconnected"))
         }
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@src/instant_messaging/L2PSMessagingPeer.ts` around lines 180 - 183, The
for-loop over this.pendingResponses introduces an unused variable named key;
update the loop to discard the first tuple element (use _ or an empty slot) so
the intent is clear and linting warnings are avoided — e.g., change the
iteration in L2PSMessagingPeer that currently reads for (const [key, pending] of
this.pendingResponses) to use a discard for the key (for (const [, pending] ...)
or for (const [_ , pending] ...)) while leaving the clearTimeout(pending.timer)
and pending.reject(new Error("Disconnected")) logic unchanged.
```

</details>

---

`28-28`: **Remove unused import `StoredMessage`.**

Static analysis indicates `StoredMessage` is imported but never used in this file.

<details>
<summary>🧹 Proposed fix</summary>

```diff
     ErrorCode,
-    StoredMessage,
 } from "./l2ps_types"
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@src/instant_messaging/L2PSMessagingPeer.ts` at line 28, The import list in
L2PSMessagingPeer.ts includes an unused symbol StoredMessage; remove
StoredMessage from the import statement (where StoredMessage is referenced) so
the file only imports actually used symbols, e.g., update the import that
currently lists StoredMessage to exclude it.
```

</details>

---

`479-486`: **Use optional chaining for cleaner code.**

The `meta` check can be simplified with optional chaining.

<details>
<summary>♻️ Proposed fix</summary>

```diff
         if (frame.requestId && this.pendingResponses.has(frame.requestId)) {
             const pending = this.pendingResponses.get(frame.requestId)!
-            const meta = pending._meta
-            if (meta && meta.types.includes(frame.type)) {
+            if (pending._meta?.types.includes(frame.type)) {
                 clearTimeout(pending.timer)
                 this.pendingResponses.delete(frame.requestId)
                 pending.resolve(frame.payload)
                 return
             }
         }
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@src/instant_messaging/L2PSMessagingPeer.ts` around lines 479 - 486, Replace
the explicit null check on pending._meta with optional chaining to simplify the
condition in L2PSMessagingPeer: instead of checking meta and then
meta.types.includes(frame.type), use pending._meta?.types.includes(frame.type)
(or meta?.types.includes(frame.type) if you keep the local variable). Keep the
rest of the logic (clearTimeout, delete from pendingResponses, resolve) intact.
```

</details>

---

`82-107`: **Consider marking non-reassigned members as `readonly`.**

Static analysis identifies several members that are never reassigned. Adding `readonly` improves type safety by preventing accidental reassignment.

<details>
<summary>♻️ Proposed fix</summary>

```diff
 export class L2PSMessagingPeer {
     private ws: WebSocket | null = null
-    private config: L2PSMessagingConfig
+    private readonly config: L2PSMessagingConfig

     // Event handlers
-    private messageHandlers: Set<L2PSMessageHandler> = new Set()
-    private errorHandlers: Set<L2PSErrorHandler> = new Set()
-    private peerJoinedHandlers: Set<L2PSPeerHandler> = new Set()
-    private peerLeftHandlers: Set<L2PSPeerHandler> = new Set()
-    private connectionStateHandlers: Set<L2PSConnectionStateHandler> = new Set()
+    private readonly messageHandlers: Set<L2PSMessageHandler> = new Set()
+    private readonly errorHandlers: Set<L2PSErrorHandler> = new Set()
+    private readonly peerJoinedHandlers: Set<L2PSPeerHandler> = new Set()
+    private readonly peerLeftHandlers: Set<L2PSPeerHandler> = new Set()
+    private readonly connectionStateHandlers: Set<L2PSConnectionStateHandler> = new Set()

     // Pending request-response waiters
-    private pendingResponses: Map<...> = new Map()
+    private readonly pendingResponses: Map<...> = new Map()

     // State
-    private messageQueue: OutgoingFrame[] = []
+    private readonly messageQueue: OutgoingFrame[] = []

     // Reconnection
-    private maxReconnectAttempts = 10
-    private baseReconnectDelay = 1000
+    private readonly maxReconnectAttempts = 10
+    private readonly baseReconnectDelay = 1000
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@src/instant_messaging/L2PSMessagingPeer.ts` around lines 82 - 107, Several
instance fields are never reassigned and should be marked readonly to improve
type safety: add the readonly modifier to messageHandlers, errorHandlers,
peerJoinedHandlers, peerLeftHandlers, connectionStateHandlers, pendingResponses,
onlinePeers, messageQueue, maxReconnectAttempts and baseReconnectDelay (leave
mutable state fields like _isConnected/_isRegistered and reconnectAttempts
unchanged). Locate these members in L2PSMessagingPeer (the declarations shown
for messageHandlers, errorHandlers, peerJoinedHandlers, peerLeftHandlers,
connectionStateHandlers, pendingResponses, onlinePeers, messageQueue,
maxReconnectAttempts, baseReconnectDelay) and prefix them with readonly so they
cannot be reassigned later.
```

</details>

---

`316-334`: **Add JSDoc comments to public event handler methods.**

Per coding guidelines, new methods should have JSDoc documentation. These public API methods would benefit from brief descriptions for IDE support and discoverability.

<details>
<summary>📝 Example JSDoc additions</summary>

```typescript
/** Register a handler for incoming messages */
onMessage(handler: L2PSMessageHandler): void { ... }

/** Register a handler for protocol errors */
onError(handler: L2PSErrorHandler): void { ... }

/** Register a handler for peer join events */
onPeerJoined(handler: L2PSPeerHandler): void { ... }

/** Register a handler for peer leave events */
onPeerLeft(handler: L2PSPeerHandler): void { ... }

/** Register a handler for connection state changes */
onConnectionStateChange(handler: L2PSConnectionStateHandler): void { ... }
```
</details>

As per coding guidelines: "Use JSDoc format for all new methods and functions".

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@src/instant_messaging/L2PSMessagingPeer.ts` around lines 316 - 334, Add JSDoc
comments to the public event registration methods to follow coding guidelines:
for each of onMessage, onError, onPeerJoined, onPeerLeft, and
onConnectionStateChange add a brief JSDoc summary sentence, an `@param` tag
documenting the handler argument and its type (e.g., L2PSMessageHandler,
L2PSErrorHandler, L2PSPeerHandler, L2PSConnectionStateHandler), and an `@returns`
tag indicating void; place the comment directly above each method declaration so
IDEs surface the descriptions and parameter types.
```

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @src/instant_messaging/L2PSMessagingPeer.ts:

• Around line 377-381: In the catch block that notifies this.errorHandlers about
  a re-registration failure inside L2PSMessagingPeer, replace the current
  String(err) stringification with the same robust pattern used at line 411 (e.g.,
  use err instanceof Error ? err.message : JSON.stringify(err,
  Object.getOwnPropertyNames(err)) or similar) so non-Error objects don't
  stringify to "[object Object]"; update the call to h(...) in the re-registration
  catch to include that improved error string.

---

Nitpick comments:
In @AGENTS.md:

• Around line 244-246: The fenced code block showing the formula "score =
  urgency + (blocked_tasks_count × 1.5)" is missing a language specifier; update
  the markdown fence to include a language such as "text" or "plaintext" so
  linters recognize it as plain text (referencing the formula symbols score,
  urgency, and blocked_tasks_count), e.g., change totext and keep the
  formula unchanged.

In @src/instant_messaging/L2PSMessagingPeer.ts:

• Around line 180-183: The for-loop over this.pendingResponses introduces an
  unused variable named key; update the loop to discard the first tuple element
  (use _ or an empty slot) so the intent is clear and linting warnings are avoided
  — e.g., change the iteration in L2PSMessagingPeer that currently reads for
  (const [key, pending] of this.pendingResponses) to use a discard for the key
  (for (const [, pending] ...) or for (const [_ , pending] ...)) while leaving the
  clearTimeout(pending.timer) and pending.reject(new Error("Disconnected")) logic
  unchanged.
• Line 28: The import list in L2PSMessagingPeer.ts includes an unused symbol
  StoredMessage; remove StoredMessage from the import statement (where
  StoredMessage is referenced) so the file only imports actually used symbols,
  e.g., update the import that currently lists StoredMessage to exclude it.
• Around line 479-486: Replace the explicit null check on pending._meta with
  optional chaining to simplify the condition in L2PSMessagingPeer: instead of
  checking meta and then meta.types.includes(frame.type), use
  pending._meta?.types.includes(frame.type) (or meta?.types.includes(frame.type)
  if you keep the local variable). Keep the rest of the logic (clearTimeout,
  delete from pendingResponses, resolve) intact.
• Around line 82-107: Several instance fields are never reassigned and should be
  marked readonly to improve type safety: add the readonly modifier to
  messageHandlers, errorHandlers, peerJoinedHandlers, peerLeftHandlers,
  connectionStateHandlers, pendingResponses, onlinePeers, messageQueue,
  maxReconnectAttempts and baseReconnectDelay (leave mutable state fields like
  _isConnected/_isRegistered and reconnectAttempts unchanged). Locate these
  members in L2PSMessagingPeer (the declarations shown for messageHandlers,
  errorHandlers, peerJoinedHandlers, peerLeftHandlers, connectionStateHandlers,
  pendingResponses, onlinePeers, messageQueue, maxReconnectAttempts,
  baseReconnectDelay) and prefix them with readonly so they cannot be reassigned
  later.
• Around line 316-334: Add JSDoc comments to the public event registration
  methods to follow coding guidelines: for each of onMessage, onError,
  onPeerJoined, onPeerLeft, and onConnectionStateChange add a brief JSDoc summary
  sentence, an @param tag documenting the handler argument and its type (e.g.,
  L2PSMessageHandler, L2PSErrorHandler, L2PSPeerHandler,
  L2PSConnectionStateHandler), and an @returns tag indicating void; place the
  comment directly above each method declaration so IDEs surface the descriptions
  and parameter types.

</details>

<details>
<summary>🪄 Autofix (Beta)</summary>

Fix all unresolved CodeRabbit comments on this PR:

- [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended)
- [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: Organization UI

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `121db510-6f49-4afe-8086-15bd20265f0d`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between a9ac32124145c8ef8dafb66b0997307ff48d7e83 and ec99a6650c543b1f004084d2464d8c846794c5a3.

</details>

<details>
<summary>⛔ Files ignored due to path filters (1)</summary>

* `.mycelium/mycelium.db` is excluded by `!**/*.db`

</details>

<details>
<summary>📒 Files selected for processing (4)</summary>

* `.mycelium/.gitignore`
* `.serena/project.yml`
* `AGENTS.md`
* `src/instant_messaging/L2PSMessagingPeer.ts`

</details>

<details>
<summary>✅ Files skipped from review due to trivial changes (1)</summary>

* .mycelium/.gitignore

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->